This document has styles in it. You may view them with a text editor such as Tex-Edit by Tom Bender or Style (1.2.1 or later) by Marco Piovanelli, or Apple SimpleText by Tom Dowdy.
If you do not care about the styles and cannot live without EasyView (a neat application by M. Akif Eyler) try opening this document with EasyView (with the same settings as TidBITS).
This documentation is intended as a little guide to the simulator; if you are in trouble, remember that Balloon Help™ is always available. You are strongly encouraged to use Balloon Help so that you can “learn by doing”, and discover some intuitive but not immediately visible functionalities. However, I have to admit that to effectively use this application (and fully understand this document), you should know something about the (wonderful?) world of microprogramming.
Why freeware?
-------------
This application is aimed at students or teachers, who are usually not millionaires. Anyway, if you have a couple (well, hundreds are even better) of bucks to spare and feel like sending them to me, you are welcome.
Do I need this application?
---------------------------
Most Mac users will probably find this application totally useless, but students or teachers may like and use it. Somebody may even have ideas about how to modify this application to fit their particular needs (or fix bugs, of course).
Overview
--------
µArchitecture Simulator models a microprogrammed processor similar to the one described in the book “Structured Computer Organization” by Andrew S. Tanenbaum. Its hardware components and instruction set are fixed (not too much, as we will see) but its microprogram is fully editable in a user friendly manner. The processor accesses a 128K Random Access Memory (borrowed from your Mac); you can easily view, modify, load or save this portion of memory. You can run programs and debug them with a step by step execution. Namely, you can advance by a conventional instruction, by a microinstruction, and even by a clock subcycle observing the internal parts of the processor.
You can work on only one document (microprogram) at a time.
The instruction set
-------------------
I largely expanded the instruction set described in the Tanenbaum’s book; the instruction list is available in a separate document. I do not like this instruction set (as most people accustomed with MC680x0’s will concur), but I had to use this one (why? the answer is in the section entitled Final thoughts).
By the way, I renamed the instruction whose name was “LOCO” in the book to “MOVQ” because incidentally LOCO #0 (that zeroes the Accumulator) had the same opcode ($7000) as MC680x0’s MOVEQ #0,D0 (that zeroes the register D0).
The instruction set is fixed; in particular, it is stored in a resource of type “OPCO”. Technically inclined people can easily modify the instruction set using ResEdit (I included a template), and even add or delete instructions. My code should assemble and disassemble instructions correctly, provided that you follow the right format.
A little explanation on the instruction set as represented in the template; first of all, the instruction class:
0 means: 4 bit opcode, 12 bit operand,
1 means: 5 bit opcode, 11 bit operand,
2 means: 8 bit opcode, 8 bit operand,
3 means: 16 bit opcode, no operand,
4 means: 16 bit opcode, 16 bit operand,
5 means: 16 bit opcode, 16 bit operand (for relative jumps),
6 means: 4 bit opcode, 12 bit operand (for relative jumps).
Length simply indicates the length of the instruction, in bytes.
Throughout this documentation, Balloon Help, and so on, I always refer to the instructions cited here as “conventional instructions”. I don’t use the term “macroinstructions” (used by Tanenbaum) to avoid confusion with “macros” such as #define in the C language.
The microprogram
----------------
I tried to simplify as much as possible the uneasy task of writing and debugging a microprogram by taking advantage of the Macintosh user interface friendliness. All of the microprogram is represented in the Microprogram window (I am sure you already guessed this one). From left to right, you can see: the conventional instructions list; the microinstructions list; a set of controls.
The microinstruction list will appear empty if you start up the simulator without opening a document. If you open the sample document supplied with this application, the microinstruction list fills up with comment strings, allowing the microprogrammer to read a brief description of the actions performed by each microinstruction. I wrote these strings using a C-style syntax, but any style is permitted, since the comment is ignored during execution.
You control the behavior of a microinstruction with the controls placed at the right side of the window. The Animation window dynamically updates to match the currently selected microinstruction.
The hardware decoding unit
--------------------------
It is the major change to the Tanenbaum’s example. Instead of decoding fetched instructions with the microprogram (a slow business), the processor duly calls a hardware mechanism. Namely, the hardware decoder sets the Micro Program Counter to the starting line of the fetched instruction. Illegal instructions are handled as in a real processor: a jump vector is read into the Program Counter from location 3 (in my example); the illegal instruction handler can be inserted into the resource of type ‘HAND’ (currently a HALT instruction).
I noticed that most conventional instructions were extracting (from the instruction opcode) the lower 12 bits (with sign extension), the lower 11 bits (again with sign extension), or the lower 8 bits (no sign extension this time). So I created the X12, X11, Lo8 registers for this purpose; the hardware decoder can set these in parallel.
These changes made the Temporary Instruction Register and mask registers useless; I ended up with one more register and a somewhat faster machine.
The registers
-------------
This processor has sixteen 16-bit registers. Three of them are read-only: they contain the constant values -1, 0, 1. Other three (X12, X11, Lo8) receive data from the hardware decoding unit. Then you can find (as in most microprocessors) a Program Counter and a Stack Pointer; a Base Pointer is provided to simplify access to local variables. The Accumulator is the register used in most of the conventional instructions of this processor. The Instruction Register is used to hold conventional instructions as they are fetched from the main memory. The other registers (A, B, C, D, E) are not visible at the conventional machine level (with my instruction set, of course), and can be used by the microprogram as scratch registers. In the example microprogram supplied, only A is used.
The assembler
-------------
It is probably the worst part in this application. It cannot process ORG directives, EQUates or literals, and error checking and reporting is very superficial. However, a correct program is guaranteed to assemble without hassles and real fast.
System 7 & around
-----------------
The simulator runs under System 7.0 or later, because System 7 is so convenient from a programmer point of view that I decided to cut off System 6 support. Let’s examine these new opportunities:
Apple Events let you drag-and-drop microprogram, memory, registers and text documents onto the µArchitecture Simulator icon. My application will respectively open the microprogram, read the memory image, restore the registers and assemble the program contained in the text document without a hitch. I also internally use Apple Events to signal important facts happening in the simulation, such as stack underflows/overflows, etc. Note that the Apple Event Manager automatically flashes an icon in the menu bar if these events happen while the application is running in the background.
The Folder Manager is used to save the Preferences document in the right folder, and to perform a safe-save of documents: the new version of a document is saved in a hidden folder (named “Temporary Items”); thus if a system crash occurs while saving, the original version remains safely unchanged, and the new version should be found in the Trash after restarting.
The Help Manager is used for Balloon Help, which provides a unique non-modal help system; I think it is very useful if the balloons are well written.
The standard Pop-up menus are used everywhere: if you find out that they redraw slowly, blame Apple (not me).
The new dialogs for opening and saving documents provide a mechanism to support System 7 stationery pads: when you open a stationery pad, the application opens the document in a new untitled window.
I also use a cool feature present in System 6.0.5 or later, allowing for neat text frames when the text is not active.
Lastly, Temporary Memory is used (when available) to execute tasks (such as reading from documents or building tables for the assembling process) requiring amounts of memory for a limited time. Under System 7 this feature is very handy, because you can play with Temporary Memory using the ordinary Memory Manager calls (under System 6 you have to use special calls).
An interesting memo for the Mac hacker
--------------------------------------
(could be a proper subject for the KON&BAL column in d e v e l o p)
Are you interested in low-level stuff? Have you read Inside Mac at least I through IV? Follow me, then.
Remember the List Manager? Remember the lClikLoop field? No? Get Inside Mac IV, page 266. Are you ready now?
So let’s assume you are handling a list (a normal, one-column one) and are writing a function that will be called repeatedly by the LClick function. Suppose you don’t want to mess up with assembly language. Plain C:
pascal Boolean myClikLoop(void)
{
register long something;
/* your code works with “something” */
return true; /* we never wish to abort LClick */
}
You play with your list, and you notice that when you click on it, and drag to the first element, it looks like you have released the mouse button. But you have not released the mouse button, really. What’s going on?
When you click on a list, you call LClick as Inside Mac IV told you. It seems that LClick may abort only in two circumstances: either you are releasing the mouse button or your lClikLoop routine returns false. But you are definitely not releasing the mouse button, nor returning false anytime: there is a clear return true statement! Everything seems right, but the thing refuses to work. You read on Inside Mac (on the same page) in an Assembly-language note: your routine should set register D0 to 1; returning 0 in register D0 aborts LClick. You add an asm { MOVEQ #1,D0 } statement before returning, but it still doesn’t work. Big headache, isn’t it?
To answer the riddle, you have to taste some details about 68K assembly language. For example, did you know that the MOVE instruction sets the condition codes? Namely, in the following assembly sequence:
MOVE.W (SP)+,Dx
TST.W Dx
BEQ @somewhere
the TST instruction is useless. (As far as I know, the Intel 8086 nearly equivalent instruction – MOV – does not set the condition codes. The PowerPC is even better: setting condition codes is an option; just append a period “.” to the instruction.)
Let’s have a look at the assembly listing of our routine (sort of):
LINK A6,#xx
MOVE.L D7,-(SP) /* saves the register we will use */
… /* the “something” variable is into D7 */
MOVEQ #1,D0 /* you added this, didn’t you? */
MOVE.B #1,8(A6) /* the compiler returns true */
MOVE.L (SP)+,D7 /* restores the register */
UNLK A6
RTS
I will now show you what happens when you execute this routine. Assume you have dragged onto the first line of the list. The Mac (the MC680x0 microprocessor) executes your routine. It gets till the RTS. Step one instruction. You now are facing a BEQ.S @somewhere instruction. The operating system is not checking explicitly your return value. It is optimized for the 680x0 family: it is assuming that you have moved the true result somewhere just before returning. This is a good assumption in 99% of the cases. In our circumstance the last MOVE is the one that restores the D7 register. So the condition codes are set according to the D7 contents! It happens that D7 (when entering the lClikLoop routine) contains the coordinates of the cell underlying the mouse. The first line is (0,0), so D7 contains a big 0. Hence the operating system thinks you have returned false (false is represented numerically as a zero). This kind of thing happens only nowadays with optimizing compilers. Back in the old days of not-too-optimizing Pascal compilers, they used to save and restore registers always with the MOVEM (MOVE Multiple registers) instruction. This instruction does not set the condition codes. A clever compiler sees that it only needs to save one register, so it generates a faster and shorter MOVE.
What’s the sequitur? If you were writing a Pascal or C function like that, and you didn’t know assembly, you’d better gibbet yourself on a tree and “swing in the breeze”.
And yes, Apple screwed up when porting this to the PowerPC; you have to do weird things to let these routines work as intended (see SimAsm.c and Globals.h).
The no-resume-event syndrome
----------------------------
No, you don’t need a doctor. Unless you are using the nifty Apple Event Manager function AEInteractWithUser and strange things happen. If you use this function to bring your application to the front, remember that the System does not send you a resume event.
Final thoughts
--------------
I was nearly forgetting to add that there is a hidden feature you can easily activate peeking around with ResEdit…
In case you are wondering, I have written this application because of a university exam.
Thanks to…
----------
My parents, who bought my first Macintosh (a Plus!) back in 1986 and pay for my studies, etc., etc.;
Alessandro Levi Montalcini, for having lent me Inside Macintosh 6 when bookstores in Torino hadn’t even heard of it; and for many, many useful suggestions (some of them still remain suggestions, unfortunately), for reporting bugs, and for having written a bunch of very useful utilities;
Alberto Ricci, for (again) many, many useful suggestions, untiring testing and bug reporting;
Peppino Ventura, who tested as always on his Mac Classic;
… and thanks to whoever has contributed to make the Mac the greatest computer ever built (as of now).
